/*
 * Copyright 2018-2023 datagear.tech
 *
 * This file is part of DataGear.
 *
 * DataGear is free software: you can redistribute it and/or modify it under the terms of
 * the GNU Lesser General Public License as published by the Free Software Foundation,
 * either version 3 of the License, or (at your option) any later version.
 *
 * DataGear is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License along with DataGear.
 * If not, see <https://www.gnu.org/licenses/>.
 */

package org.datagear.analysis;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Reader;
import java.io.Writer;
import java.util.List;
import java.util.Map;

/**
 * {@linkplain TplDashboardWidget}资源管理器。
 * <p>
 * 此类通过{@linkplain DashboardWidget#getId()}来管理{@linkplain TplDashboardWidget}的模板及其他资源。
 * </p>
 * 
 * @author datagear@163.com
 *
 */
public interface TplDashboardWidgetResManager
{
	/**
	 * 获取默认资源编码。
	 * 
	 * @return
	 */
	String getDefaultEncoding();

	/**
	 * 指定名称的资源是否存在。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @param name
	 *            模板或者其他资源名称
	 * @return
	 */
	boolean exists(String id, String name);

	/**
	 * 获取指定名称资源的输入流。
	 * <p>
	 * 使用{@linkplain TplDashboardWidget#getTemplateEncoding()}、或者{@linkplain #getDefaultEncoding()}编码。
	 * </p>
	 * 
	 * @param widget
	 * @param name
	 *            模板或者其他资源名称
	 * @return
	 * @throws IOException
	 */
	Reader getReader(TplDashboardWidget widget, String name) throws IOException;

	/**
	 * 获取指定名称资源的输入流。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @param name
	 *            模板或者其他资源名称
	 * @param encoding
	 *            资源编码，为{@code null}或空则使用默认编码
	 * @return
	 * @throws IOException
	 */
	Reader getReader(String id, String name, String encoding) throws IOException;

	/**
	 * 获取指定名称资源的输出流。
	 * <p>
	 * 使用{@linkplain TplDashboardWidget#getTemplateEncoding()}、或者{@linkplain #getDefaultEncoding()}编码。
	 * </p>
	 * 
	 * @param widget
	 * @param name
	 *            模板或者其他资源名称
	 * @return
	 * @throws IOException
	 */
	Writer getWriter(TplDashboardWidget widget, String name) throws IOException;

	/**
	 * 获取指定名称资源的输出流。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @param name
	 *            模板或者其他资源名称
	 * @param encoding
	 *            资源编码，为{@code null}或空则使用默认编码
	 * @return
	 * @throws IOException
	 */
	Writer getWriter(String id, String name, String encoding) throws IOException;

	/**
	 * 获取指定名称资源的输入流。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @param name
	 *            模板或者其他资源名称
	 * @return
	 * @throws IOException
	 */
	InputStream getInputStream(String id, String name) throws IOException;

	/**
	 * 获取指定名称资源的输出流。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @param name
	 *            模板或者其他资源名称
	 * @return
	 * @throws IOException
	 */
	OutputStream getOutputStream(String id, String name) throws IOException;

	/**
	 * 将指定目录下的所有文件作为资源拷入。
	 * <p>
	 * 拷入后，目录下所有子文件的相对路径名（比如：<code>some-file.txt</code>、<code>some-directory/some-file.png</code>），即可作为此类的资源名称使用。
	 * </p>
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @param directory
	 * @throws IOException
	 */
	void copyFrom(String id, File directory) throws IOException;

	/**
	 * 将指定{@linkplain TplDashboardWidget#getId()}的所有资源拷贝至目标目录。
	 * 
	 * @param id
	 * @param directory
	 * @throws IOException
	 */
	void copyTo(String id, File directory) throws IOException;

	/**
	 * 将指定源{@linkplain TplDashboardWidget#getId()}（{@code sourceId}）的所有资源拷贝为目标{@linkplain TplDashboardWidget#getId()}（{@code targetId}）资源。
	 * 
	 * @param sourceId
	 * @param targetId
	 * @throws IOException
	 */
	void copyTo(String sourceId, String targetId) throws IOException;

	/**
	 * 获取指定资源上次修改时间。
	 * 
	 * @param id   {@linkplain TplDashboardWidget#getId()}
	 * @param name 模板或者其他资源名称
	 * @return
	 */
	long lastModified(String id, String name);

	/**
	 * 列出所有资源。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @return
	 */
	List<String> list(String id);

	/**
	 * 删除指定ID的所有资源。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 */
	void delete(String id);

	/**
	 * 删除指定资源。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @param name
	 *            模板或者其他资源名称
	 */
	void delete(String id, String name);
	
	/**
	 * 重命名指定资源。
	 * 
	 * @param id
	 *            {@linkplain TplDashboardWidget#getId()}
	 * @param srcName 源资源名
	 * @param destName 目标资源名
	 * @return 已改名的所有资源映射表，结构为：<code>原资源名 -&gt; 新资源名</code>
	 */
	Map<String, String> rename(String id, String srcName, String destName) throws IOException;
}
